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ABOUT THIS CHAPTER 


Warning: 


This chapter describes the Palette Manager, a Toolbox addition 


You 


e 


e 


This chapter has not been updated to reflect changes 
that are available on systems using 32-Bit QuickDraw. 
information on 32-Bit QuickDraw, please refer to the 
documentation (available on "Phil & Dave's Excellent 


Version). 


should already be familiar with 


the 
the 
the 
the 
the 


Resource Manager 


and improvements 


For 


further 


32-Bit QuickDraw 
CD: The Release 


for the Macintosh 
II. The Palette Manager, as its name implies, supports the use of a collection 
of colors when you draw objects with Color QuickDraw. The Palette Manager 
provides routines your application can call to manage shared color resources, to 
provide exact colors for imaging, or to initiate color table animation. It also 
describes the data structures of color palettes and how the Palette Manager 
communicates with Color QuickDraw. 


basic concepts and structures behind Color QuickDraw, particularly 
calls that set RGB colors and use color patterns 
Color Manager and the RGB color model used by Color QuickDraw 


Window Manager 
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ABOUT THE PALETTE MANAGER 


The Palette Manager is responsible for monitoring and establishing the color 
environment of the Macintosh II. It gives preference to the color needs of the 
front window, making the assumption that the front window is of greatest 
interest to the user. 


The Palette Manager is initialized during the first InitWindows call after 
system startup, and continues to run as needed whenever windows are moved. If 
the front window is an old-style window, or if it has no assigned palette, the 
Palette Manager establishes the color environment using a default palette. 


For many simple applications, the colors in the default palette will suffice. 
This is especially true of applications that use no color, for the Palette 
Manager ensures that black and white are always available. 


Suppose, as an example, that you wish to draw an object using 32 different 
shades of gray. The default palette won't provide enough different levels of 
gray. Color QuickDraw will match your request as well as it can, so the object 
will look something like you expected, but probably not exactly the way you 
wanted. What you need is a convenient way to change the color environment for 
this window automatically, so that plenty of gray colors will be available each 
time your window comes to the front. The Palette Manager was designed to solve 
this problem. 


You begin by creating a data structure called a color palette. This is normally 
done by creating a resource of type 'pltt', but you can create it within your 
application using the Palette Manager routines if you prefer. In the palette for 
the gray drawing, you would include 32 palette entries, each one specifying a 
different shade of gray. In addition, each entry would contain information 
telling the Palette Manager that you require the color to be an exact match, a 
process that is described later in this chapter. 


You next use a Palette Manager routine to associate your palette with a 
particular window. If that window is the front window, or whenever it becomes 
the front window, the Palette Manager checks the current color environment to 
determine if the 32 shades of gray are available, exactly as requested. If they 
aren't available, the Palette Manager changes the color environment, adding as 
many colors as it can, at the expense of windows in the background. Finally, if 
the color environment has changed, the Palette Manager updates the background 
windows. 


The Palette Manager routines make each step of this process reasonably simple. 
The Palette Manager also handles multiple devices and different screen 
resolutions, so your application need not attempt to provide for all possible 
machine configurations. In addition, the Palette Manager routines provide for 
several different uses of color, for example color table animation, by building 
a color index mode upon the more general Color QuickDraw RGB Model. This color 
index model is described in the following section. 
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The Color Index Model 


Many video devices implement color using an indexed color model: a pixel value 
in the video device's memory is used as an index into a color table. The RGB 
value found in the table at that index position appears on the display device. 
In general, the resolution of the values in the video card's color look-up table 
is much higher than the resolution provided by the index itself. 


The Palette Manager is primarily designed for use with this indexed color model; 
it can also be used with direct or fixed video devices. (See the Color Manager 
chapter for an explanation of the different video device types.) However, the 
indexed color model has several advantages. It requires less memory than a 
direct color model. It is also faster because less information must be written 
to the display device, due to the reduced resolution. In addition, it allows the 
use of a technique called color table animation. Color table animation involves 
changing the index entries in the video device's color table to achieve a change 
in color, as opposed to changing the pixel values themselves. ALl pixel values 
corresponding to the altered index entries suddenly appear on the display device 
in the new color. By careful selection of index values and the corresponding 
colors, you can achieve a number of special animation effects. 


The indexed color model also has several disadvantages. Because the range of 
pixel values is generally low, the number of colors that can be shown at any one 
time is correspondingly low. Colors on such devices are a shared resource, just 
as the visible area of a display device is shared by several windows. If desk 
accessories and application windows wish to use different sets of colors, a 
problem of color contention arises. If color table animation is also used 
(assuming the target display device supports it), the problem of contention can 
become acute. 


Although the problems presented by color table animation and color contention 
can be solved using Color QuickDraw and Color Manager routines, the available 
solutions are somewhat cumbersome. The Palette Manager handles these problems 
for your application by providing an indexed color model built upon the more 
general RGB model. Your application allocates a Palette object and fills it with 
RGB colors, along with information describing how each color should be managed. 
When the Palette Manager detects that the target display device allows an 
indexed color model, it manages the allocation of that device's color resources. 
As colors are requested and allocated, it updates its information and adjusts 
the color matching scheme accordingly. 


Color Usage 
The Palette Manager uses one of four methods for selecting colors: 


¢ Courteous colors have no special properties. For such colors, the Palette 
Manager relies upon Color QuickDraw to select appropriate pixel values. 
Colors with specified usages that can't be satisfied by the Palette 
Manager will default to courteous colors. This occurs, for example, when 
drawing to a device with no color look-up table, such as a direct or fixed 
device. Courteous colors don't change the color environment in any way. 

¢ Tolerant colors cause a change in the color environment unless the fit to 
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the best matching available color falls within a separately specified 
tolerance value. 

e Animating colors are reserved by a palette and are unavailable to (and 
can't be matched by) any other request for color. 

e Explicit colors always generate the corresponding entry in the device's 
color table. 


These color types are specified when using Palette Manager routines by using the 
following constants: 


CONST { Usage constants } 


pmCourteous = $0000; 
pmDithered = $0001; {reserved for future use} 
pmTolerant = $0002; 
pmAnimated = $0004; 
pmExplicit = $0008; 


When you specify colors for a palette within a 'pltt' resource, you will usually 
assign the same usage value to each color in the palette. However, if for some 
reason a particular color must be used differently than the other colors in the 
palette, it can be assigned a different usage value, either within the resource 
file, or within the application through use of the SetEntryUsage routine. 


The sections that follow provide more information on these color types. 
Courteous Colors 


Courteous colors are provided for two reasons. First, they are a convenient 
placeholder. If your application uses only a small number of colors you can 
place each of them in a palette, ordered according to your preference. Suppose 
you have a palette resource which consists of a set of eight colors, namely 
white, black, red, orange, yellow, green, blue, and violet, in that order, each 
with a usage specified as courteous. Assuming further that the palette resource 
ID number matched that of a color window (myColorWindow) you opened earlier, the 
following calls will paint a rectangle (myRect) in yellow (palette entry 4, 
where white is Q): 


SetPort (myColorWindow) ; 
PmForeColor (4); 
PaintRect (myRect) ; 


This is exactly analogous to the following sequence of calls made using Color 
Quickdraw routines, where yellowRGB is of type ColorSpec: 


with yellowRGB do begin {done once during your initialization} 


red := $FFFF; 
green := $FFFF; 
blue := $0000 
end; 


SetPort (myColorWindow) ; 
RGBForeColor (yellowRGB) ; 
PaintRect (myRect); 
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The second reason for providing courteous colors is not immediately apparent. 

It involves how colors are selected for palettes which use animation. The 
Palette Manager has access to all palettes used by all windows throughout the 
system. When deciding which of a device's colors to allocate for animation, it 
checks each window currently drawn on that device to see which colors the 
windows are using. It then chooses the color which is least used and reserves 
that for animation. In the first example shown above, the Palette Manager would 
try to avoid the eight colors used in your palette, even though they are just 
courteous colors. In the second example it would have no knowledge of your 
colors and might steal them unnecessarily, and when your window is redrawn the 
selected colors might not be as close to the desired colors as they previously 
were. If you intend to use only a limited number of colors it is therefore best 
to place them in the window's palette so the Palette Manager will know about 
them. 


Tolerant Colors 


Tolerant colors allow you to change the current color environment according to 
your needs. When your window becomes the frontmost window on a device its 
palette and the colors contained therein are given preference. Each tolerant 
color is compared to the best unique match available in the current color 
environment (for each device on which the window is drawn). When the difference 
between your color and the best available match is greater than the tolerance 
you have specified the Palette Manager will modify the color environment to 
provide an exact match to your color. 


The tolerance value associated with each palette entry is compared to a measure 
of the difference between two RGBColor values. This difference is an 
approximation of the distance between the two points as measured in a Cartesian 
coordinate system where the axes are the unsigned red, green, and blue values. 
The distance formula used is shown below: 


A RGB = maximum of (abs(Redl—Red2), abs(Greenl—Green2), abs(Bluel—Blue2) ) 


A value of $5000 is generally sufficient to allow matching without updates in 
reasonably well-balanced color environments. A tolerance value of $0000 means 
that only an exact match is acceptable. Any value of $0xxx, other than $0000, is 
reserved, and should not be used in applications. 


If your palette requires more colors than are currently available the Palette 
Manager will check to see if any other palette has reserved entries for 
animation. If so it will dereserve them and make them available for your 
palette. If you ask for more than are available on a device, the Palette 
Manager cannot honor your request. However, you can still call PmForeColor for 
such colors; as mentioned earlier, such colors default to courteous colors. 
Color QuickDraw will still select the best color available, which of course must 
match one of the colors elsewhere in your palette since the Palette Manager will 
only run out of colors after it has given your palette all that it has. Two 
exceptions to this rule are noted below. See the "Black, White, and Palette 
Customization" section and the "Palette Prioritization" section describing the 
interaction among colors of different usages in a single palette. 


Animating Colors 
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Animating colors allow you to reserve device indexes for color table animation. 
Each animating color is checked to see if it already has a reserved index for 
the target device. If it does not, the Palette Manager attempts to find a 
Suitable index. This is done by checking all windows to see what colors they 
use, and which device indexes match those colors. The least frequently used 
indexes are then reserved for your palette. The reservation process is 
analogous to the Color Manager call ReserveEntry. The device index and its 
corresponding color value is removed from the matching scheme used by Color 
Quickdraw; you cannot draw with it by calling RGBForeColor. However, when you 
call PmForeColor the Palette Manager will locate the reserved index and 
configure your window's port to draw with it. On multiple devices this will 
likely be a different index for each device, but this process will be invisible 
to your application. 


After reserving one or more device indexes for each animating entry it detects, 
the Palette Manager will change the color environment to match the RGB values 
specified in the palette. To use an animating color you must first draw with it 
using PmForeColor or PmBackColor. To effect color table animation you can use 
either AnimateEntry (for a single color) or AnimatePalette (for a contiguous set 
of colors). These calls are described in the section titled 

"Palette Manager Routines". 


Explicit Colors 


Explicit colors are provided as a convenience for users who wish to use colors 
in very special ways. The RGB value in a palette is completely ignored if a 
color is an explicit color. Explicit colors cause no change in the color 
environment and are not counted for purposes of animation. Explicit colors 
always match the corresponding device index. A PmForeColor call with a 
parameter of 12 will place a value of (12 modulo (MaxIndex+1)) into the 
foreground color field of your window's cGrafPort, where MaxIndex is the maximum 
available index for each device under consideration. When you draw with an 
explicit color, you get whatever color the device index currently contains. 


One interesting use for explicit colors is that it allows you to monitor the 
color environment on a device. For example, you could draw a grid of 256 
explicit colors, 16-by-16, in a small window. The colors shown are exactly 
those in the device's color table. If color table animation is taking place 
Simultaneously the corresponding colors in the small window will animate as 
well. If you display such a window on a 4-bit device, the first 16 colors will 
match the 16 colors available in the device and each row thereafter will be a 
copy of the first row. 


However, the main purpose for explicit colors is to provide a convenient indexed 
color interface. Using the Color Manager, you can establish a known color 
environment using the SetEntries routine on each device of interest. You can 
then easily select any of these colors for drawing by setting your window's 
palette to contain as many explicit colors as are in the target device with the 
greatest number of indexes. PmForeColor will configure the cGrafPort to draw 
with the index of your choice. 


Warning: You should not use explicit colors in this fashion if you intend 
your application to coexist in multi-application environments such 
as those provided by MultiFinder™ or A/UX™ or when using color desk 
accessories that depend upon the Palette Manager. However, for 
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certain types of applications, especially those which are written 
for a known device environment, explicit colors will tend to make 
indexed color manipulation much more convenient. 


Palette Prioritization 


To make the best use of the Palette Manager you should understand how it 
prioritizes the colors you request. Prioritization is important only when the 
ActivatePalette routine is called. This occurs automatically when your window 
becomes the front window, or when you call ActivatePalette after changing one or 
more of the Palette's colors or usage values. 


Explicit and courteous colors are ignored and are not considered during 
prioritization. They are important only during calls to PmForeColor and 
PmBackColor, or when scanning all palettes to check which colors are in use. Of 
the remaining two types of colors, animating colors are given preference. 
Starting with the first entry in your window's palette (entry 0), the Palette 
Manager checks to see if it is an animating entry. It checks each animating 
entry to see if the entry has a reserved index for each appropriate device. If 
the animating entry has no reserved index, the Palette Manager selects an index 
and reserves it for animation. This process continues until all animating 
colors have been satisfied or until the available indexes are exhausted. 


Tolerant entries are handled next. Each tolerant entry is assigned its own, 
unique index until all tolerant colors have been satisfied. The Palette Manager 
then calculates for each entry the difference between the desired color and the 
color associated with the selected index. If the difference exceeds the 
tolerance you have specified, the selected device entry is marked to be changed 
to the desired color. 


When as many animating and tolerant entries have been matched as are possible, 
the Palette Manager checks to see if the color environment needs to be modified. 
If modifications are needed, it forces the device environment to a known state 
(overriding any calls made to the Color Manager outside the Palette Manager) and 
calls the Color Manager to change the device's color environment accordingly 
(with the SetEntries routine). 


Finally, if the color environment on a given device has changed, the Palette 
Manager checks to see if this change has impacted any other window in the 
system. If another window was affected, that window is checked to see if it 
specifies an update in the case of such changes. Applications can use the 
SetPalette routine to specify if a window should be updated. If so, an 
InvalRect is performed using the bounding rectangle of the device which has been 
changed. 


As mentioned earlier, when you specify a sequence of tolerant entries, the 
indexes assigned are guaranteed to be unique provided there are sufficient 
indexes available. If you specify a pair of tolerant entries that can match 
each other within tolerance, they will each be matched to a different index, and 
the color environment changed accordingly (if necessary). If this is not the 
result you desire, then you should convert one of the two to a courteous entry. 
In the best case the courteous color will, at drawing time, match the exact 
color you have requested for it, a service provided automatically by Color 
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Quickdraw. In the worst case, the courteous color will match its tolerant 
counterpart, because that color is at least guaranteed to be provided when your 
window is frontmost (again assuming enough entries are available). 


Black, White, and Palette Customization 


Due to the "first-come, first-served" nature of the Palette Manager, you can 
prioritize your palettes to customize the color environment automatically for a 
variety of display depths. Black and white should generally be the first two 
colors in your palette. Color Quickdraw, in order to support standard Quickdraw 
features, works best when black and white are located at the end and beginning, 
respectively, of each device's color table. The Palette Manager enforces this 
rule, and thus the maximum number of indexes available for animating or tolerant 
colors is really the maximum number of indexes minus two. However, if black or 
white are present in your palette, they won't be counted as unique indexes if 
any of your tolerant entries match them within the specified tolerance. 


With black and white as the first two colors in your palette, you have matched 
the two colors the Palette Manager will allow for a 1-bit device. The next two 
colors should be assigned to the two you wish to have should the device be a 2- 
bit device. Likewise the first 16 colors should be the optimal palette entries 
for a 4-bit device. And, for future expandability, the first 256 colors (if you 
need that many) should be the optimal palette entries for an 8-bit device. A 
palette is limited to 4095 entries. 
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COLOR PALETTE RECORDS 


The basic data structure for a color palette is the ColorInfo record. It 
consists of the following: 


TYPE 
ColorInfo = RECORD 
CiRGB: RGBColor; {absolute RGB values} 
ciUsage: INTEGER {color usage information} 
ciTolerance: INTEGER; {tolerance value} 
ciFlags: INTEGER; {private field} 
ciPrivate: LONGINT; {private field} 
END; 


Field descriptions 


ciRGB The ciRGB is the absolute RGB value defined by Color QuickDraw. 

ciUsage The ciUsage field contains color usage information that 
determines the properties of a color. 

ciTolerance The ciTolerance is a value used to determine if a color is close 
enough to the color chosen; if the tolerance value is exceeded, 
the preferred color is rendered in the device's color table for 
the selected index. 

ciFlags The ciFlags field is used internally by the Palette Manager. 

ciPrivate The ciPrivate field is used internally to store information 
about color allocation: not for use by application. 


The data structure for a color palette is made up of an array of ColorInfo 
records, plus other information relating to the use of the colors within the 
palette. The 'pltt' resource is an image of the Palette data structure. 


Note: The palette is accessed through the Palette Manager routines only: 
do not attempt to directly access any of the fields in this data 


structure. 
TYPE 

PaletteHandle = *PalettePtr; 

PalettePtr = “Palette; 

Palette = RECORD 
pmEntries: integer; {entries in pmInfo} 
pmDataFields: array [0..6] of integer; {private fields} 
pmInfo: array [0..0] of ColorInfo; 

END; 


Field descriptions 


pmEntries The pmEntries field contains the number of entries in the pmTable. 

pmDataFields The pmDataFields field contains an array of integers that are 
used internally by the Palette Manager. 

pmInfo The pmInfo field contains an array of ColorInfo records. 
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USING THE PALETTE MANAGER 


The InitPalettes routine is always called before any other Palette Manager 
routines. It initializes the Palette Manager, if necessary, and searches the 
device list to find all active CLUT devices. 


Normally, a new color palette is created from a 'pltt' resource, using 
GetNewPalette. To create a palette from within an application, use NewPalette. 
Whichever method is used to create the palette, the SetPalette routine can then 
be used to render the Palette on the display device. The DisposePalette 
procedure disposes of the entire palette. 


The ActivatePalette routine is called by the Window Manager every time your 
window's status changes. When using the Palette Manager routines, you should use 
ActivatePalette after you have made changes to a palette. GetPalette is used to 
return a handle to the palette currently associated with a specified window. 


To use color table animation, you can change the colors in a palette and on 
corresponding devices with the AnimateEntry and AnimatePalette routines. 
GetEntryColor, SetEntryColor, GetEntryUsage, and SetEntryUsage allow an 
application to access and modify the fields of a palette. 


CTab2Palette copies the specified color table into a palette, while Palette2CTab 
does the opposite, and copies a palette into a color table. Each routine resizes 
the target object as necessary. 
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COLOR PALETTES IN A RESOURCE FILE 


The format of a palette resource (type 'pltt') is an image of the palette 
structure itself. 
record are reserved for future use. 


The private fields in both the header and in each ColorInfo 


The following table shows a sample palette resource with 16 entries as it would 
appear within a resource file. 


Table 1-Sample Palette Resource 


Resource Format 


data 'pltt' 


$"0010 
$"FFFF 


9000 
FFFF 


0000 
F37D 


648A 
C6FF 


Ago 
0000 
08C2 
C000 
8000 
C3DC 
281A 
C2FF 
FFFF 
AD85 
0000 


(1, 


0000 
FFFF 


0000 
052F 


028C 
9EC9 


0000 
D400 
06A2 
C000 
8000 
8160 
12CC 
0000 
04F1 
FFFF 
FFFF 


0000 
0002 


0002 
0002 


0002 
0002 


0002 
0002 
0002 
0002 
0002 
0002 
0002 
0002 
0002 
0002 
0002 


0000 
0000 


0000 
0000 


0000 
0000 


0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 


0000 
0000 


0000 
0000 


0000 
0000 


0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 


Description 


0000 
0000 


0000 
0000 


0000 
0000 


0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 


"My palette resource") { 


0000" 
0000" 


0000" 
0000" 


0000" 
0000" 


0000" 
0000" 
0000" 
0000" 
0000" 
0000" 
0000" 
0000" 
0000" 
0000" 
0000" 


/* header - $0010 (16) entries */ 
/* white - used in all screen */ 


/*depths */ 
/* black */ 


/* yellow - used in depths >= 2*/ 


/* bits/pixel */ 
/* orange */ 


/* blue green - used in depths */ 
/*>= 4 bits/pixel */ 


/* green */ 
/* blue */ 
/* red */ 


/* light gray */ 


/* medium gray */ 


/* beige */ 
/* brown */ 


/* olive green */ 
/* bright green */ 


/* sky blue 


/* violet */ 


A 
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PALETTE MANAGER ROUTINES 


The Palette Manager routines described in this section are designed for use with 
the Macintosh II. 


Initialization and Allocation 
PROCEDURE InitPalettes; 


InitPalettes initializes the Palette Manager. It searches for devices which 
Support a Color Look-Up Table (CLUT) and initializes an internal data structure 
for each one. This call is made by InitWindows and should not have to be made 
by your application. 


FUNCTION NewPalette (entries: INTEGER; srcColors: CTabHandle; 
srcUsage, srcTolerance: INTEGER) : PaletteHandle; 


NewPalette allocates a new Palette object which contains a table of colors with 
enough room for "entries" colors. It fills the table with as many RGB values 
from srcColors as it has or as it can fit. It sets the usage field of each 
color to srcUsage and the tolerance value of each color to srcTolerance. If no 
color table is provided (srcColors = NIL) then all colors in the palette are set 
to black (red = $0000, green = $0000, blue = $0000 ). 


FUNCTION GetNewPalette (paletteID: INTEGER) : PaletteHandle; 


GetNewPalette fetches a Palette object from the Resource Manager and initializes 
it. If you open a new color window with GetNewCWindow, this routine is called 
automatically with paletteID equal to the window's resource ID. A palette 
resource is identified by type 'pltt'. A paletteID of 0 is reserved for the 
system palette resource which is used as the default palette for noncolor 
windows and color windows without assigned palettes. 


PROCEDURE DisposePalette (srcPalette: PaletteHandle) ; 
DisposePalette disposes of a Palette object. If the palette has any entries 


allocated for animation on any display device, these entries are relinquished 
prior to deallocation of the object. 


Interacting With the Window Manager 
PROCEDURE ActivatePalette (srcWindow: WindowPtr) ; 


ActivatePalette is the routine called by the Window Manager when your window's 
status changes: for example, when it opens, closes, moves, or becomes 
frontmost. You should call ActivatePalette after making changes to a palette 
with the utility routines described below. Such changes do not take effect 
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until the next call to ActivatePalette, thereby allowing you to make a series of 
palette changes without any immediate change in the color environment. 


If srcWindow is frontmost, ActivatePalette examines the information stored in 
the palette associated with srcWindow and attempts to provide the color 
environment described therein. It determines a list of devices on which to 
render the palette by intersecting the port rect of the srcWindow with each 
device. If the intersection is not empty, and if the device has a Color Look-Up 
Table (CLUT), then ActivatePalette checks to see if the color environment is 
sufficient. If a change is required, ActivatePalette calls the Color Manager to 
reserve or modify the device's color entries as required. It then generates 
update events for all affected windows which desire color updates. 


PROCEDURE SetPalette (dstWindow: WindowPtr; srcPalette: PaletteHandle; 
cUpdates: BOOLEAN); 


SetPalette changes the palette associated with dstWindow to srcPalette. It also 
records whether the window wants to receive updates as a result of a change to 
its color environment. If you want dstWindow to be updated whenever its color 
environment changes, set cUpdates to TRUE. 


FUNCTION GetPalette (srcWindow: WindowPtr) : PaletteHandle; 
GetPalette returns a handle to the palette associated with srcWindow. If no 


palette is associated with srcWindow, or if srcWindow is not a color window, 
GetPalette returns NIL. 


Drawing With Color Palettes 


These routines enable applications to specify foreground and background drawing 
colors with the assistance of the Palette Manager. Substitute these for Color 
Quickdraw's RGBForeColor and RGBBackColor routines when you wish to use a color 
from a palette. You may still use RGBForeColor and RGBBackColor in the normal 
way whenever you wish to specify drawing colors, for example when you wish to 
use a color which is not contained in your palette. 


PROCEDURE PmForeColor (dstEntry: INTEGER) ; 


PmForeColor sets the RGB and index forecolor fields of the current cGrafPort 
according to the palette entry of the current cGrafPort (window) corresponding 
to dstEntry. For courteous and tolerant entries, this call performs an 
RGBForeColor using the RGB color of the palette entry. For animating colors it 
will select the recorded device index previously reserved for animation (if 
still present) and install it in the cGrafPort. The RGB forecolor field is set 
to the value from the palette entry. For explicit colors PmForeColor places 
(dstEntry modulo (MaxIndex+1)) into the cGrafPort, where MaxIndex is the largest 
index available in a device's CLUT. When multiple devices are present with 
different depths, MaxIndex varies appropriately for each device. 


PROCEDURE PmBackColor (dstEntry: INTEGER) ; 


PmBackColor sets the RGB and index backcolor fields of the current cGrafPort 
according to the palette entry of the current cGrafPort (window) corresponding 
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to dstEntry. For courteous and tolerant entries, this call performs an 
RGBBackColor using the RGB color of the palette entry. For animating colors it 
will select the recorded device index previously reserved for animation (if 
still present) and install it in the cGrafPort. The RGB backcolor field is set 
to the value from the palette entry. For explicit colors PmBackColor places 
(dstEntry modulo (MaxIndex+1)) into the cGrafPort, where MaxIndex is the largest 
index available in a device's color table. When multiple devices are present 
with different depths, MaxIndex varies appropriately for each device. 


Color Table Animation 


PROCEDURE AnimateEntry (dstWindow: WindowPtr; dstEntry: INTEGER; 
srcRGB: RGBColor) ; 


AnimateEntry changes the RGB value of dstEntry in the palette associated with 
dstWindow to the color specified by srcRGB. Each device for which an index has 
been reserved is immediately modified to contain the new value. This is not 
considered to be a change to the device's color environment since no other 
windows should be using the animated entry. If the palette entry is not an 
animating color, or if the associated indexes are no longer reserved, no 
animation is performed. 


If you have blocked color updates in a window, by using SetPalette with CUpdates 
set to FALSE, you may observe undesired animation. This will occur when 
ActivatePalette reserves device indexes for animation which are already used in 
the window. Redrawing the window, which normally occurs as the result of a 
color update event, will remove any animating colors which do not belong to it. 


PROCEDURE AnimatePalette (dstWindow: WindowPtr; srcCTab: CTabHandle; 
srcIndex,dstEntry,dstLength: INTEGER) ; 


AnimatePalette performs a function similar to AnimateEntry, but it acts upon a 
range of palette entries. Beginning at srcIndex (which has a minimum value of 
0), the next dstLength entries are copied from srcCTab to dstWindow's palette, 
beginning at dstEntry. If srcCTab is not sufficiently large to accommodate the 
request, aS many entries are modified as possible and the remaining entries are 
left unchanged. 


Manipulating Palette Entries 


PROCEDURE GetEntryColor (srcPalette: PaletteHandle; srcEntry: INTEGER; 
VAR dstRGB: RGBColor); 


GetEntryColor allows your application to access the color of a palette entry. 
The color may be modified by using the SetEntryColor routine described below. 


PROCEDURE SetEntryColor (dstPalette: PaletteHandle; dstEntry: INTEGER; 
srcRGB: RGBColor); 


SetEntryColor provides a convenient way for your application to modify the color 
of a single palette entry. When you perform a SetPaletteEntry, the entry is 
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marked as having changed, but no change occurs in the color environment. The 
change will be effected upon the next call to ActivatePalette. Modified entries 
are marked such that the palette will be updated even though no update might be 
required by a change in the color environment. 


PROCEDURE GetEntryUsage (srcPalette: PaletteHandle; srcEntry: INTEGER; 
VAR dstUsage,dstTolerance: INTEGER) ; 


GetEntryUsage allows your application to access the usage fields of a palette 
entry, namely ciUsage and ciTolerance. These fields may be modified by using 
the SetEntryUsage routine described below. 


PROCEDURE SetEntryUsage (dstPalette: PaletteHandle; dstEntry: INTEGER; 
srcUsage,srcTolerance: INTEGER) ; 


SetEntryUsage provides a convenient way for your application to modify the color 
of a single palette entry. When you perform a SetEntryUsage, the entry is 
marked as having changed, but no change occurs in the color environment. The 
change will be effected upon the next call to ActivatePalette. Modified entries 
are marked such that the palette will be updated even though no update might be 
required by a change in the color environment. If either myUsage or myTolerance 
are set to $FFFF (—1) they will not be changed. 


This call is provided to allow easy modifications to a palette created with 
NewPalette or modified by CTab2Palette. In such cases the ciUsage and 
ciTolerance fields are homogeneous since only one value can be designated for 
each. You will typically call SetEntryUsage after those calls in order to 
adjust and customize your palette. 


PROCEDURE CTab2Palette (srcCTab: CTabHandle; dstPalette: PaletteHandle; 
srcUsage,srcTolerance: INTEGER) ; 


CTab2Palette is a convenience procedure which copies the fields from an existing 
ColorTable record into an existing Palette record. If the records are not the 
same size then the Palette record is resized to match the number of entries in 
the ColorTable record. If dstPalette has any entries allocated for animation on 
any display device, these entries are relinquished prior to copying the new 
colors. If you wish to effect color table animation you can change the colors 
in a palette, and on corresponding devices, with the AnimateEntry and 
AnimatePalette routines described above. Changes made to a palette by 
CTab2Palette don't take effect until the next ActivatePalette is performed. If 
either the color table handle or the palette handle are NIL, no operation is 
performed. 


PROCEDURE Palette2CTab (srcPalette: PaletteHandle; dstCTab: CTabHandle) ; 


Palette2CTab is a convenience procedure which copies all of the colors from an 
existing Palette record into an existing ColorTable record. If the records are 
not the same size then the ColorTable record is resized to match the number of 
entries in the Palette record. If either the palette handle or the color table 
handle are NIL, no operation is performed. 
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SUMMARY OF THE PALETTE MANAGER 


Constants 
CONST 
{ Usage constants } 
pmCourteous = $0000; 
pmDithered = $0001; {not implemented} 
pmTolerant = $0002; 
pmAnimated = $0004; 
pmExplicit = $0008; 
Data Types 
TYPE 
ColorInfo = RECORD 
CiRGB: RGBColor; {absolute RGB values} 
ciUsage: INTEGER {color usage information} 
ciTolerance: INTEGER; {tolerance value} 
ciFlags: INTEGER; {private field} 
ciPrivate: LONGINT; {private field} 
END; 
PaletteHandle = *PalettePtr; 
PalettePtr = “Palette; 
Palette = RECORD 
pmEntries: integer; {entries in pmInfo} 
pmDataFields: array [0..6] of integer; {private fields} 
pmInfo: array [0..0] of ColoriInfo; 
END; 
Routines 
Initialization and Allocation 
PROCEDURE InitPalettes; 
FUNCTION NewPalette (entries: INTEGER; srcColors: CTabHandle; 
srcUsage,srcTolerance: INTEGER) : PaletteHandle; 
FUNCTION GetNewPalette (paletteID: INTEGER) : PaletteHandle; 


PROCEDURE 
Interactin 


PROCEDURE 
PROCEDURE 


DisposePalette (srcPalette: PaletteHandle) ; 
g with the Window Manager 


ActivatePalette (srcWindow: WindowPtr) ; 
SetPalette (dstWindow: WindowPtr; srcPalette: PaletteHandle; 
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cUpdates: BOOLEAN); 
FUNCTION GetPalette (srcWindow: WindowPtr) : PaletteHandle; 


Drawing with Color Palettes 


PROCEDURE PmForeColor (myEntry: INTEGER) ; 
PROCEDURE PmBackColor (myEntry: INTEGER) ; 


Color Table Animation 


PROCEDURE AnimateEntry (dstWindow: WindowPtr; dstEntry: INTEGER; 
srcRGB: RGBColor); 

PROCEDURE AnimatePalette (dstWindow: WindowPtr; srcCTab: CTabHandle; 
srcIndex,dstEntry,dstLength: INTEGER) ; 


Manipulating Palettes 


PROCEDURE GetEntryColor (srcPalette: PaletteHandle; srcEntry: INTEGER; 
VAR dstRGB: RGBColor); 

PROCEDURE SetEntryColor (dstPalette: PaletteHandle; dstEntry: INTEGER; 
srcRGB: RGBColor); 

PROCEDURE GetEntryUsage (srcPalette: PaletteHandle; srcEntry: INTEGER; 
VAR dstUsage,dstTolerance: INTEGER) ; 

PROCEDURE SetEntryUsage (dstPalette: PaletteHandle; dstEntry: INTEGER; 
srcUsage,srcTolerance: INTEGER) ; 

PROCEDURE CTab2Palette (srcCTab: CTabHandle; dstPalette: PaletteHandle; 
srcUsage,srcTolerance: INTEGER) ; 

PROCEDURE Palette2CTab (srcPalette: PaletteHandle; dstCTab: CTabHandle) ; 


Assembly Language Information 


; Palette Manager Equates 


pmCourteous EQU $0000 ;courteous colors 
pmDithered EQU $0001 ;reserved for future use 
pmTolerant EQU $0002 ;tolerant colors 
pmAnimated EQU $0004 ;animating colors 
pmExplicit EQU $0008 ;explicit colors 


» ColoriInfo structure 


ciRGB EQU $0000 sabsolute RGB values 

ciUsage EQU $0006 ;color usage information 

ciTolerance EQU $0008 stolerance value 

ciFlags EQU $000A ;private field 

ciPrivate EQU $000C ;private 

ciSize EQU $0010 ;size of the ColorInfo data structure 


: Palette structure 


pmEntries EQU $0000 ;entries in pmInfo 
pmInfo EQU $0010 ;color info 
pmHdrSize EQU $0010 ;size of Palette header 
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Further Reference: 


Resource Manager 

Color QuickDraw 

Color Manager 

Window Manager 

Technical Note #211, Palette Manager Changes in System 6.0.2 
32-Bit QuickDraw Documentation 


END OF DOCUMENT 
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